home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Panorama / Panorama - Disk 19D (1987-07-22)(Pacific North-West Amigas Club)[WB].zip / Panorama - Disk 19D (1987-07-22)(Pacific North-West Amigas Club)[WB].adf / PipeHandler1.2 / README < prev    next >
Text File  |  1987-06-28  |  7KB  |  197 lines
  1. README file for pipe-handler (version 1.2 13-Jun-87)
  2. ====================================================
  3.  
  4. This program and source are freely distributable, provided the file headers
  5. remain intact (i.e., my name is on them!!!).
  6.  
  7. Ed Puckett accepts no responsibility for others' use of this program.
  8.  
  9. ...but you shouldn't have any problems!
  10.  
  11.  
  12. WHAT IS THIS?
  13. -------------
  14. Pipe-handler is an AmigaDOS device.  It supports OPEN, CLOSE, READ and
  15. WRITE (of course), and also LOCK, EXAMINE, EXNEXT.  Therefore, you can
  16. CD to the handler, use Dir and List on it, and ASSIGN to it as well as
  17. to individual pipes in it.  Here is a complete list of the packet
  18. types it supports:
  19.  
  20.     MODE_READWRITE
  21.     ACTION_FINDINPUT  (syn: MODE_READONLY, MODE_OLDFILE)
  22.     ACTION_FINDOUTPUT (syn: MODE_NEWFILE)
  23.     ACTION_END
  24.     ACTION_READ
  25.     ACTION_WRITE
  26.     ACTION_LOCATE_OBJECT
  27.     ACTION_COPY_DIR
  28.     ACTION_FREE_LOCK
  29.     ACTION_EXAMINE_OBJECT
  30.     ACTION_EXAMINE_NEXT
  31.     ACTION_PARENT
  32.  
  33. You cannot Seek() pipes nor can you create pipe subdirectories.
  34.  
  35.  
  36. INSTALLATION
  37. ------------
  38. 1. Perform the following:
  39.     <uudecode phl.uue to produce pipe-handler-l>
  40.     <uudecode ph.uue  to produce pipe-handler>
  41.     Copy pipe-handler-l L:pipe-handler-loader
  42.     Copy pipe-handler   L:pipe-handler
  43.  
  44. 2. Add to S:Startup-Sequence (do not include !'s - they denote start of line):
  45.     !Mount P:
  46.     !Dir >NIL: P:
  47.  
  48. 3. Add to DEVS:Mountlist (do not include !'s - they denote start of line):
  49.     !P:     Handler = L:pipe-handler-loader
  50.     !     Stacksize = 3000
  51.     !     Priority = 5
  52.     !#
  53.  
  54. 4. Reboot
  55.  
  56.  
  57. NOTES ON INSTALLATION
  58. ---------------------
  59. * The handler, once installed, requires approximately 18k of memory.  This
  60.   memory cannot be reclaimed (unless you reboot and do not load the handler).
  61.   Each pipe requires additional memory while it exists (its buffer size +
  62.   about 100 bytes or so).
  63.  
  64. * You can skip the reboot, and just perform the "Mount" and "Dir" from the
  65.   startup-sequence manually.
  66.  
  67. * After the "Dir", the pipe-handler is loaded into the system, and the files
  68.   "L:pipe-handler-loader" and "L:pipe-handler" will not be accessed until the
  69.   next reboot.    This means you may remove them from L: if you want (until
  70.   next    reboot).  I do this because I copy L: into Ram:.
  71.  
  72. * TO CHANGE THE HANDLER NAME: change "P:" to whatever you want (e.g., "PIPE:")
  73.   in the following 2 files:
  74.     DEVS:Mountlist        (1 occurrence)
  75.     S:Startup-Sequence    (2 occurrences)
  76.  
  77. * Feel free to shorten or otherwise change the names "pipe-handler-loader"
  78.   and "pipe-handler".  Just be sure to reflect those changes in
  79.   "S:Startup-Sequence" and "DEVS:Mountlist".
  80.  
  81.  
  82. TAPS
  83. ----
  84. The handler also supports "taps".  These are essentially tees off of the
  85. pipe, and can specify any destination to which a copy of the pipe's stream
  86. is to be sent.    One interesting application of this is tapping to a
  87. CON: window; you can then see what is going through the pipe, and you
  88. can also stop pipe throughput by typing a character into this window.
  89. Taps can also be other pipes.
  90.  
  91. For an interesting demo of taps, EXECUTE the file "tap_demo".
  92.  
  93. All pipe I/O is asynchronous, so you will not be able to lock up the
  94. handler by stopping one of its pipes.  A single reader / single writer
  95. discipline in enforced.
  96.  
  97. Pipe buffers are dynamically allocated.  A pipe is removed from memory
  98. when all openers have closed it and it is empty.  The size of a pipe buffer
  99. may be specified as part of its name.  Otherwise, pipe buffers have a default
  100. size of 4096 bytes.
  101.  
  102. Pipes behave in most respects like ordinary files.  Some differences follow:
  103. Pipes block for writing (i.e., the write request is suspended) when the
  104. pipe's buffer is full, and block for reading when the pipe's buffer is
  105. empty.    Thus, pipes are sort of like bounded ram: files.  EOF is returned
  106. for reading when the pipe's buffer is empty and no process has the pipe
  107. open for writing.
  108.  
  109.  
  110. NAME SYNTAX
  111. -----------
  112. In addition to the pipe's identifier, its name can specify its size
  113. and a tap.  The syntax is
  114.  
  115.     name[/size][/[tapname]]
  116.  
  117. where the parts enclosed in "[]" are optional.  The size must begin with
  118. a digit in the range 0-9.  If first digit is not "0", the size is
  119. interpreted as decimal.  If the size begins with "0x", it is interpreted
  120. as hexadecimal.  Otherwise, if the size begins with "0" but not "0x", it
  121. is interpreted as octal.
  122.  
  123. If an empty tapname is specified, the default tap CON:10/15/300/70/name
  124. is used (where "name" is the pipe's name given).
  125.  
  126.  
  127. EXAMPLES OF PIPE NAMES
  128. ----------------------
  129.  
  130. The following assume that the pipe-handler is mounted as device P:
  131.  
  132. P:x                Opens a pipe named "x" with buffer size 4096
  133.  
  134. P:x/100             Opens a pipe named "x" with buffer size 100
  135.  
  136. P:hold/             Opens a pipe named "hold" with buffer size
  137.                 4096, and also opens a window which displays
  138.                 the data which passes through the pipe.
  139.  
  140. P:xyzzy/plugh            Opens a pipe named "xyzzy" with buffer size
  141.                 4096, and also directs the data passing
  142.                 through into the file "plugh".  (Note that
  143.                 taps may be specified without specifying
  144.                 a size.)
  145.  
  146. P:thru/0x40/ram:thru-log    Opens a pipe named "thru" with buffer size
  147.                 64 (decimal), and also directs the data
  148.                 passing through the pipe into the file
  149.                 "ram:thru-log".
  150.  
  151.  
  152. WHAT IS THIS SILLY "LOADER" FILE?
  153. ---------------------------------
  154. According to _The_AmigaDOS_Manual_ (Bantam Books, Feb 1986), page 291:
  155.  
  156.     If you write your device handler in C, you cannot use the automatic
  157.     load and process creation provided by the kernel.  In this case you
  158.     must load the code yourself . . . .
  159.  
  160. Well, I know others have gotten around this, and I did, too.  The "prelude"
  161. version of the handler (see the Makefile) does it all with one file.
  162. However, I noticed that doing it this way, the handler would take about
  163. 3 seconds to "Mount" (after first access to it).  This made me very nervous -
  164. visions of wild linking through memory, etc.  The loader version mounts
  165. almost immediately.
  166.  
  167. Anyway, due to my (possibly unfounded) paranoia, I instead use the BCPL-like
  168. assembly module "pipe-handler-loader" which LoadSeg()'s pipe-handler.  There
  169. are undoubtedly better ways of handling this, but this works and, for me,
  170. it is not too annoying to put up with the extra file.
  171.  
  172.  
  173. COMPILATION
  174. -----------
  175. The supplied C source files were compiled with Lattice v3.03.
  176. The assembly programs were assembled using the Commodore Assembler.
  177.  
  178. See the Makefile for information on creating a debugging version
  179. (this puts up a window and tells you what packets are received by
  180. the handler - fun!).  Basically, you just compile with a -DDEBUG
  181. option and link in the debugging modules.
  182.  
  183. The Makefile will make either a "prelude" version (no "loader file)
  184. or a "loader" version (the default).
  185.  
  186. I use an EXECUTE file "cc" to driver the compiler.  It is supplied.
  187.  
  188.  
  189. INQUIRIES / COMMENTS / SUGGESTIONS
  190. ----------------------------------
  191. Ed Puckett
  192.  
  193. US Mail:  MIT Branch PO - PO Box 61
  194.       Cambridge, MA  02139
  195.  
  196. E Mail:  ...!ihnp4!mit-eddie!mit-oz!qix
  197.